PEP 1, 12 and template: update style - #5082

I don't think we should change the template. There's nothing wrong with the existing all-caps headers except that it doesn't conform to our current standard. Consistency is useful, but what does PEP 8 say about consistency? 😄

Since we already have so many PEPs that are using this template, changing it does introduce a larger inconsistency! All those PEPs using the all-caps headers will be inconsistent and I don't think we should go back and change them.

Yes, we have to accept drift when we add a new section (such as Change History) or re-order them (like Rationale moved to after Specification), but there were some substantive reasons behind those changes.

If anything, I'd prefer to drop the changes in PEP 1/12 and only change the template :D

PEP 8 has hobgoblins and also:

Consistency within a project is more important. Consistency within one module or function is the most important.

Indeed, individual PEPs are more like standalone documents than our main docs, which form an editorial whole.

And knowing when to be inconsistent:

• We don't apply the style guide as rigorously to PEPs as the docs, and I usually don't bother with the same style nits in PEP reviews.

• Changing the template is for consistency within single PEPs, and for future ones, and not worrying about all the historical ones.

The docs style guide mirrors the PEP 8 text above about consistency in smaller units:

In the Python documentation, the use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule. If you add a section to a chapter where most sections are in title case, you can either convert all titles to sentence case or use the dominant style in the new section title.

PEP 84x

Looking at the 84x PEPs (skipping 840 that doesn't use the usual template and anyway only has inconclusive single-word headers!):

841	842	843	844

These authors added their own subheadings in Sentence case, so are now inconsistent with the Title Case main headings. If the main template headings were Sentence case, these would be consistent.

PEP 83x

Looking at the 83x:

• Title Case headings + Title Case subheadings: 830, 831, 835, 836

• Title Case headings + Sentence case subheadings: 832, 833, 834, 837, 838, 839

Altogether 83x+84x have 10 with Sentence case subheadings, 4 with Title Case.

PEP xxx

Getting an LLM to categorise the whole bunch:

The majority with Title Case headings use Sentence case subheadings. Changing the default would have improved internal consistency.

I'd argue many of the TC + TC authors were being consistent and just matched the main heading style, so if we flipped the template, they would have remained consistent with Sc + Sc, not Sc + TC.

And interestingly, there are none with Sc + TC.

Flipping the template would match both our style, and authors' own preference.

Changing PEP 1's headers is fine in isolation since it's not a template, but ... is it worth it? We have so many all-caps headers in the PEPs, I'm not so sure.